<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <meta http-equiv="Content-Style-Type" content="text/css">
  <title></title>
  <meta name="Generator" content="Cocoa HTML Writer">
  <meta name="CocoaVersion" content="921">
  <style type="text/css">
    p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
    p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
    span.s1 {letter-spacing: 0.0px}
  </style>
</head>
<body>
<p class="p1"><span class="s1"><b>Input and Data Validation</b></span></p>
<p class="p1"><span class="s1">The only input for this library expected to come from outside sources is the token, to cardspace_process_token. Several precautions are taken around this method:</span></p>
<p class="p1"><span class="s1">Lengths are not assumed from the input provided. A length parameter must be given</span></p>
<p class="p1"><span class="s1">The value is passed into libxml2 for parsing. Any error will cause an immediate exit</span></p>
<p class="p1"><span class="s1">The data is processed by libxmlsec, decrypting based on the local private key.</span></p>
<p class="p1"><span class="s1">Once the data is decrypted, it is not assumed to be issued by a trusted party. The message is checked for schema validation (against a relaxed schema, as the Microsoft Cardspace implementation does not send valid SAML 1.1 assertions).</span></p>
<p class="p1"><span class="s1">The message conditions are checked for validity by SAML rules. The timestamps are compared to the current time (or a preconfigured time, allowed for testing purposes), audience restrictions are evaluated, and do not cache conditions are consumed as we do not expose or retain the raw assertion. Any other conditions will cause failure.</span></p>
<p class="p1"><span class="s1">The message is also checked for validity by information card rules. The issuer is required to be the ‘self’ issuer defined in the information card profile.</span></p>
<p class="p1"><span class="s1">The token signature is verified, and the public key included is given as an attribute through the callback mechanism.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1">Caveats</span></p>
<p class="p1"><span class="s1">The implementation makes the assumption that a significant amount of other internet-facing software makes, that the XML tools in use are also doing proper handling of input</span></p>
<p class="p1"><span class="s1">Replay detection requires state, while the library itself is stateless. The application using the library is responsible for replay detection. [DW: Adding an explicit replay detection callback is a week 10 activity. This is currently done by reporting AssertionID as a attribute</span></p>
<p class="p1"><span class="s1">No checking is done to make sure PPID is generated correctly by the selector, or that the public key used was generated correctly by the selector. It is assumed both of these actions are not possible, as we do not have the internal card id or master key.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Authentication</b></span></p>
<p class="p1"><span class="s1">The library does not perform authentication itself, instead giving information usable for performing an authentication action.</span></p>
<p class="p1"><span class="s1">PPID is a poor choice of authentication, if this value is ever shared a ‘fake’ authentication can be created easily by creating a new key pair, signing a SAML assertion with the PPID contained within, and encrypting with the RP’s private key. For this reason, the public key is also exposed to the application as an attribute, and the application writer is encouraged to not share or display PPID values.</span></p>
<p class="p1"><span class="s1">Attributes are exposed through a callback mechanism to the application. It is assumed the application will cache these values for future web requests, associating them with the user’s browser session via cookies or some other mechanism such as SSL session identifiers.</span></p>
<p class="p2"><br></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Authorization</b></span></p>
<p class="p1"><span class="s1">This library does not perform authentication or authorization itself, instead giving information usable for performing the authentication action. It is not recommended that any information contained within a self-issued card be used for authorization; instead the authentication can be used to associate pre-existing authorization data with a session.</span></p>
<p class="p2"><br></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Configuration Management</b></span></p>
<p class="p1"><span class="s1">Configuration of the library is done entirely through directives against the ‘context’ object. No direct configuration format is specified or supported, however the public and private keys are currently only supported within PEM-encoded files on disk.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Sensitive Data</b></span></p>
<p class="p1"><span class="s1">The CardSpace profile unfortunately requires tokens to be encrypted with the public SSL key of a RP, requiring the private key to be available to decrypt the token. For this reason, it is suggested that the card processing logic be isolated, within another process, ideally on another piece of hardware which has no other exposure other than the interface provided to process cards.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1">It is expected that a higher level language will abstract the card processing logic to take a token as input and return some object with all of the attributes. If these languages provide these data types to be serialized, creating a remote interface for isolation should be simple.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1">Also, the user’s attributes may be sensitive information. The library performs no caching of any user attributes, encouraging only caching by application developers of the ppid, public key, and a replay detection cache based on the non-identifying AssertionID</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Session Management</b></span></p>
<p class="p1"><span class="s1">This library makes no attempt at providing for session management. For additional information, see authentication and authorization topics above.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Cryptography</b></span></p>
<p class="p1"><span class="s1">The data is processed by libxmlsec, decrypting based on the local private key.</span></p>
<p class="p1"><span class="s1">The token signature is verified, and the public key included is given as an attribute through the callback mechanism.</span></p>
<p class="p1"><span class="s1">The public key is exposed as an attribute, as it provides a mechanism for identifying the user.</span></p>
<p class="p1"><span class="s1">The library requires access to the SSL private key, see ‘Sensitive data’ above.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Parameter Manipulation</b></span></p>
<p class="p1"><span class="s1">The library is isolated from the HTTP/HTML frameworks gathering the user submission.</span></p>
<p class="p1"><span class="s1">The XML parser is assumed to be able to do with malformed data.</span></p>
<p class="p1"><span class="s1">The XML encryption/signature library has not been evaluated for resistance to attacks based on referencing remote resources or performing overly complex manipulations of data.</span></p>
<p class="p1"><span class="s1">The resulting data within the self-issued card can neither be trusted for authenticity or validity. Applications need to verify that no scripting commands (for example) are embedded within the reported fields.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1">Exception Management</span></p>
<p class="p1"><span class="s1">No exceptions are provided, as there are not alternate or exceptional flows to take tat have been currently evaluated which differ based on results. Failures are indicated by methods returning a NULL pointer rather than an object, or false from an interface. A language wishing typed exceptions could build them from the last reported logger message.</span></p>
<p class="p2"><br></p>
<p class="p1"><span class="s1"><b>Auditing and Logging</b></span></p>
<p class="p1"><span class="s1">Debug and informational logging is currently performed only minimally. </span></p>
</body>
</html>
